docs: add Factory use-case navigation - #895

What this feature does

Warp Factories recipes help teams configure bounded development workflows in an existing factory: issue triage, implementation, pull request review, incident investigation, UI verification, and SDLC coordination. Each recipe names its inputs, outputs, verification steps, and human decision points.

Summary

PRs #896–#901 are merged into this parent. The current pushed head, 56a1d158fe2ebec89328091be48c186a1002a1f9, contains the overview, sidebar navigation, all six completed recipes, and the combined-review fixes. This PR targets main.

The combined-review fixes are committed and pushed in 56a1d158. Local validation results are recorded below; GitHub CI and independent review run separately against the pushed head.

Changes

Current pushed scope

• Adds an overview and six recipe routes under factories/use-cases/, with a matching sidebar group.
• Covers GitHub, GitLab, Azure DevOps, Linear, and Jira where each workflow has supported intake.
• Keeps incident investigation read-only until a separate human fix request, UI verification evidence in existing PR comments, specification approval with people, and merging under normal repository controls.
• Links setup and reference details to their canonical owners rather than duplicating provider documentation.

Combined-review fixes — pushed in 56a1d158

• Sends triage intake to the foreman for triage-only delegation, clarification relay, and results; distinguishes new intake from existing conversations.
• Makes the Jira triage and implementation examples mutually exclusive using current-label conditions, preserves cumulative catch-all exclusions, and documents human promotion.
• Makes standalone openings and descriptions attributable to Warp Factories, replaces vague overview cards with outputs and stopping points, and tightens task-first setup instructions.
• Makes standalone PR-ready and re-review intake a deliberate choice alongside SDLC's internal review, while retaining revision and merge-completion handlers.
• Preserves provider names and fragment targets in generated Markdown through clone-only tab normalization. Adds serializer regressions and a CI test hook; browser tab HTML remains unchanged.

Reusable style-guide, drafting/review skill, template, and evaluation-input changes are isolated in #965 on rrenk/recipe-drafting-guidance; they are not part of this PR.

Content design plan

Audience and JTBD: An engineering lead or developer configuring an existing factory for a recurring development task who needs a bounded starting point and observable results.

Problem: Product references explain individual factory primitives but do not connect them into these six task-oriented recipes.

Goals: Help readers choose the smallest useful workflow, configure its routing and instructions, test its boundaries, and recognize when human input is required.

Purpose and value: A conceptual chooser connects to six combined feature/procedure pages. The recipes own workflow sequencing and stopping points; the quickstart and provider, agent, skill, webhook, hosting, and definition references own general setup and syntax.

Content type: Conceptual overview plus six combined feature/procedure pages; existing titles and purposes are retained.

Skill and template: draft_feature_doc / .agents/templates/feature-doc.md, with a card-based overview.

Scope: Issue intake through reviewed changes and evidence. Broad factory setup stays with the overview/quickstart. Autonomous production mitigation, deployment, monitoring, and automatic merging are not promised.

Editorial verdict: Removed repeated table introductions and vague cards without removing required setup context, credentials, provider limits, activation-before-testing, or copyable prompt safeguards. The changes correct composed routing rather than promising that retargeting an automation migrates existing work.

AEO/source rationale

Peec's Warp project was reviewed for September 28–October 27, 2026. The observed tracked prompts were:

• “what does a complete software factory workflow look like” — low volume bucket.
• “how to integrate AI coding agents into a software factory workflow” — high volume bucket.
• “what’s the best way to review code changes that an AI agent made?” — high volume bucket.

An owned how-to recommendation supports practical software-factory setup material. These signals inform workflow vocabulary and the recipe chooser; they do not measure demand for every recipe. No matching active or archived triage or incident prompt was found in that review, which is not proof of no demand. No citation-lift measurement is claimed. Broader deploy/monitor query fan-outs do not expand these recipes' approved scope.

Verification evidence

These local validation results apply to the changes committed as 56a1d158 on top of 75e79f29. They are not a claim that GitHub CI or live end-to-end checks have passed:

• Serializer: 11 tests passed, including hidden/nested/repeated tab labels, explicit targets, code/list preservation, and byte-identical browser HTML.
• Typecheck: 0 errors, 0 warnings; 7 existing hints.
• Heading-variable tests: 5 passed.
• Full build: 408 pages; heading/TOC checks passed for 3,435 entries; homepage JSON-LD passed.
• Focused rendered-page checks: 851 internal navigation/content/fragment links across seven pages, no broken targets; all descriptions 50–160 characters; all recipe compression checks passed; provider sections retained in generated Markdown.
• Style lint: no errors; 10 contextual glossary warnings for provider names, UI controls, and routing-list labels were reviewed.
• Fifteen extracted configuration blocks passed revision-pinned generated schemas, including composed trigger replacements, the verifier agent, and Sentry webhook. Negative controls rejected invalid events, unknown filter keys, and contradictory matchers.
• The actual documented Jira filters passed a source-faithful current-label routing matrix: triage only, ready only, both, neither, unrelated labels, wrong project, unknown labels, and preservation of an additional prior exclusion.

Source and schema revision: warp-server@27c9fb8049c27037c15833ab711f7b7a131bf6ac. Consulted:

• logic/ai/ambient_agents/automations/provider_jira.go:371–390 — current-label session filtering.
• logic/ai/ambient_agents/automations/filter.go:138–143 and model/types/triggers/matcher.go:19–26 — inclusion/exclusion predicates and array shorthand.
• logic/ai/ambient_agents/factory_external_key_routing.go:755–810 — continued work retains the initial agent configuration.
• logic/factorysource/defaults/prompts/triage.md:87–89 — clarification through the orchestrator.
• Factory definition generated schemas and canonical product references for the configuration examples.

The rollout helper was rerun at that named revision. Checked-in production configuration supports the relevant session path; broad keyword matches also included unrelated gated features. Source/configuration evidence is not a live deployment, delivery, or end-to-end check.

Unverified claims

• Production parser execution was unavailable locally because no Go toolchain is installed. Schema checks and the Python predicate port are not described as Go parser execution; cross-resource resolution still needs the real validator.
• Local tests ran on Node 25.2.1. CI-supported Node 22 validation is tracked by the pushed head's GitHub checks; no compatible runtime was installed locally for this task.
• No live factory, provider delivery, conversation-continuation test, production credential use, signed Sentry delivery, UI interaction, or deployment was performed. An engineer must confirm current availability and runtime behavior before merge.
• Prompts express requested behavior, not deterministic guarantees. Runtime permissions, provider authentication, artifact-sharing policy, and human repository controls remain necessary.

Documentation risk

Risk: engineering-review-required
Rationale: Adds public multi-agent workflows, provider routing examples, webhook configuration, and generated-Markdown behavior.
Docs override: none

PR stack and human review

Child PRs #896, #897, #898, #899, #900, and #901 are merged into this parent.

Review the combined routing and continued-conversation policy, provider/event constraints, credential and evidence-sharing boundaries, and separation between standalone and SDLC review. The eight addressed combined-review threads were resolved after 56a1d158 was pushed; that does not substitute for independent review or pending engineering confirmation.

Implementation and evidence context: https://staging.warp.dev/conversation/022d43d0-010c-4bc2-b6b7-58523e50176a

Co-Authored-By: Warp agent@warp.dev